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Notices 

The information contained in this document is subject to change without notice. 

Hewlett-Packard provides the following material “as is” and makes no warranty 
of any kind with regard to this manual, including, but not limited to, the implied 
warranties of merchantability and fitness for a particular purpose. Hewlett- 
Packard shall not be liable for errors contained herein or direct, indirect, special, 
incidental or conseguential damages (including lost profits) in connection with 
the furnishing, performance, or use of this material whether based on warranty, 
contract, or other legal theory. 

Some states do not allow the exclusion of implied warranties or the limitation 
or exclusion of liability for incidental or consequential damages, so the above 
limitation and exclusions may not apply to you. This warranty gives you specific 
legal rights, and you may also have other rights which vary from state to state. 

Hewlett-Packard assumes no responsibility for the use or reliability of its software 
on equipment that is not furnished by Hewlett-Packard. 

Warranty. A copy of the specific warranty terms applicable to your Hewlett- 
Packard product and replacement parts can be obtained from your local Sales 
and Service Office. 

This document contains information which is protected by copyright. All rights 
are reserved. Reproduction, adaptation, or translation without prior written 
permission is prohibited, except as allowed under the copyright laws. 

Restricted Rights Legend. Use, duplication or disclosure by the U.S. Government 
is subject to restrictions as set forth in subparagraph (c)(l)(ii) of the Rights in 
Technical Data and Computer Software clause in DFARS 252.227-7013. Rights 
for non-DoD U.S. Government Departments and Agencies are as set forth in 
FAR 52.227- 19(c)(1,2). 

Use of this manual and flexible disc(s), or tape cartridge(s), or CD-ROM supplied 
for this pack is restricted to this product only. Additional copies of the programs 
can be made for security and back-up purposes only. Resale of the programs in 
their present form or with alterations, is expressly prohibited. 
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PEX and PEXlib are trademarks of the X Consortium. 
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New editions of this manual will incorporate all material updated since the 
previous edition. 

The manual printing date and part number indicate its current edition. The 
printing date changes when a new edition is printed. (Minor corrections and 
updates which are incorporated at reprint do not cause the date to change.) The 
manual part number changes when extensive technical changes are incorporated. 

June 1996 ... Edition 1. This manual is valid for HP PEX 5.1v4 on all HP9000 
Series 700 Computers running HP-UX 10.20. 
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HP PEX 


Introduction 

The Version 4 release of HP PEX 5.1 brings high-performance 3D graphics 
through the X server to the HP9000, Series 700 family of 3D Color Workstations. 
The HP PEX server and HP PEXlib client software extend the capabilities of 
the X Window System and provide integrated 3D distributed graphics in an 
open systems environment. 

The Hewlett-Packard implementation is equipped with a number of features 
for enhanced performance and interoperability. These features and their 
operation are explained in the book HP PEX Implementation and Programming 
Supplement. 

Among other features, the HP PEX product includes an integrated, on-line 
hypertext tutorial. And because the PEX standard is an industry standard, 
Hewlett-Packard is able to offer learning products documentation from O’Reilly 
& Associates, Inc.—publishers widely acclaimed for making information easy to 
learn and use. 

Read Me First 

This document contains important information about the HP PEX product that 
is essential for those who program using HP PEXlib. This document provides 
information on some known behaviors that could affect the outcome of your 
workstation setup and subsequent operation of HP PEXlib programs. 

This version of HP PEX is supported on the HP 9000, Series 700 3D Color 
Workstations running HP-UX 10.20 or later, and HP CDE 1.0 or HP VUE 3.0. 
However, you can choose not to use HP CDE or HP VUE and use only the X 
Windows environment instead. 

The PowerShade product provides full, 3D surfaces and lighting functionality. 
HP workstations without PowerShade provide 3D wireframe with flat shading. 
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In addition, the HP PEX Developer’s Environment requires the header hies and 
development tools for the X Window System Version 11, Release 5, available in 
the HP-UX Developer’s Toolkit or the ANSI/C HP-UX Developer’s Toolkit. 


HP PEX Product Filesets 

The HP PEX developer’s product consists of the following filesets: 


PEXlib Eileset 

Contents 

PEX5-PRG 

Contains headers for the PEXlib programming environment 

PEX5-EXAMPLES 

Contains source code and makefiles for the example programs 
from both Hewlett-Packard and O’Reilly & Associates. 

PEX5-HELP 

Contains the hypertext, interactive on-line information system 
comprising a PEX tutorial and PEX 5.1v4 reference. 


The filesets PEX5-RUI and PEX5-DEM0S are included in the PEX Runtime 
environment. 

If, for any reason, you must reinstall either the X Window System or the HP-UX 
operating system, you must also reinstall HP PEX. See the section “Information 
for System Administrators” in Chapter 2 of the HP PEX Implementation and 
Programming Supplement. 
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Installation Verification 

If you are setting up a new workstation, or have already installed the HP-UX 
10.20 operating system, all HP PEX software may already be preloaded for you. 
If the HP PEX developer’s software is not loaded on your system, you will have to 
install it before you can use it. Since the HP PEX Developer’s Kit is part of the 
HP-UX Developer’s Toolkit, follow the installation instructions for the HP-UX 
Developer’s Toolkit, and include the PEX-related hlesets for installation. 

To determine whether or not the PEX 3D run-time libraries are installed, 
run /opt/graphics/PEX5/demos/verify_install. If HP PEX resides on your 
system, verify_install will create a window and draw a rotating “PEX cube” 
in it—a cube with three letter-shaped holes drilled in it, one per face, one in each 
dimension. Depending upon your hardware and color map settings, you may 
experience “technicolor”—the distracting effect of displayed objects changing 
colors as color maps with different contents are installed. (Color map installation 
is typically under control of a window manager, and is often triggered by moving 
the window focus from one window to another.) If there are problems running 
this test program, the error messages will point you to a solution. 

To determine whether you have the HP PEX Developer’s software installed, check 
for the existence of the following include hie: 

/opt/graphics/PEX5/include/XHR5/Xll/PEX5/PEX.h 

Checking the Device Files 

Devices specified in X server screen configuration hies must correspond to existing 
device hies with appropriate permission. If you don’t already have the appropriate 
device hie, you must create it using the mknod command. For information on 
mknod see the Graphics Administration Guide , the HP-UX Reference Manual 
and/or Using the X Window System. 

Read the ReleaseNotes File for Time-Critical Information 

Before you begin using the HP PEX product, it is important to check on¬ 
line hies. You will hnd time-critical information in the HP PEX product’s 
“Release Notes” hie, /opt/graphics/PEX5/RelNotes, which contains important 
information about the HP PEX product hies. This includes information about 
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utility programs used for setting up workstations properly and which provide 
interoperability of programs. 

Also, look in the README hies that may be found in the various subdirectories of 
the HP PEX product’s main directory (pex) 1 . 


Using Example Programs, Demonstrations, and Utilities 

The directory [pex) 1 contains various example programs and demonstrations 
listed below. It also contains important utilities for running these programs 
with PEXlib extensions supported by Hewlett-Packard. See the README hie in 
this directory for more information. 

■ The program examples from the PEXlib Programming Manual by O’Reilly & 
Associates are installed in the directory {ora-examples) 1 . 

A README hie in this directory contains instructions for using these programs. 
It specifically describes the use of book_utils .h, which contains the macros 
and declarations used by these O’Reilly programs. An important fact to note 
about the O’Reilly utility procedure source, book_utils. c, is that the source 
shipped with HP PEX has been modihed by Hewlett-Packard to provide for 
improved interoperability. 

We recommend that you look at the HP-modihed book_utils.c hie and at 
the other utility hies for ways to improve the interoperability of your programs 
and of programs you port from other vendors’ platforms. 

■ HP PEXlib demonstrations are located in the /opt/graphics/PEX5/demos 
directory. A README hie in this directory explains how to use the example 
programs. 

■ Example programs developed by Hewlett-Packard are installed in the (hp- 
examples) 1 directory. A README hie in this directory explains how to use the 
example programs. 

■ Example programs that demonstrate portability and functionality of the CGE 
extensions are in (cge-examples) 1 . 

1 The actual path names of directories in angle brackets depend on the hie system 
structure. See the Graphics Administration Guide for details. 
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■ Programming utilities for visual selection and color map creation provided by 
the CGE PEX vendors are in (cge-utils) 2 . 

■ Other important programming utilities are provided in the directory ( pex- 
utils) 2 . 

By listing the hies in these directories, you will see utilities designed for improving 
the interoperability of programs between workstations of different manufacturers, 
resolving color map issues, selecting visuals and creating windows for HP 
workstations. These utilities are documented in a README in the same directory. 

PEXlib Reference Pages 

The reference pages for PEX 5.1v4 are presented via CDE and VUE Help, the 
hypertext-capable on-line help systems. (This on-line help works even if you’re 
only using regular X windows; you don’t need to be running HP CDE or HP 
VUE.) You can start the on-line help system by executing (vhelp) 2 bin/pexman”. 

The Hewlett-Packard PEX product supplements the standard PEXlib reference 
pages with reference pages on the HP utilities mentioned above. These are also 
accessed via pexman. 

Accompanying Product Documentation 

Information about HP PEX/PEXlib is found in these books that are available 
with the developer’s product: 

■ HP PEX Implementation and Programming Supplement —Information and 
instructions for those who will install and use HP PEX/PEXlib. Enables you 
to deal with implementation-dependent characteristics of HP workstations as 
well as accessing and operating the on-line information and tutorial system. 

■ PEXlib Programming Manual —Written by Tom Gaskins, published by O’Reilly 
& Associates, it provides beginners in PEXlib with the basics for getting 
started. 

■ PEXlib Programming Reference —Also published by O’Reilly & Associates, is 
a reference to the PEXlib procedures based on the MIT document. 


2 The actual path names of directories in angle brackets depend on the hie system 
structure. See the Graphics Administration Guide for details. 
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■ HP PEX On-Line Information —HP integrates this on-line, hypertext tutorial 
based on the “Getting Started” chapter from the PEXlib Programming Manual. 

m Portable Programming with CGE PEX 5.1 —A CGE-standard document that 
provides information on how to write applications that will be portable and 
interoperable across different vendors’ platforms. 


Documentation Published by O’Reilly and Associates 

O’Reilly and Associates are no longer printing the following manuals: 

■ PEXlib Programming Manual 

■ PEXlib Programming Reference 

Although they are no longer orderable from O’Reilly and Associates, you may 
still find these manuals in bookstores that carry technical documentation. 
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